Inside Macintosh: QuickDraw GX Objects /

Chapter 6 - Transform Objects / Transform Objects Reference

Functions / Transforming Shapes by Modifying Shape Geometries

GXMoveShapeTo

You can use the GXMoveShapeTo function to move a shape to a specified position.

void GXMoveShapeTo(gxShape target, Fixed x, Fixed y);

target

A reference to the shape you want to move.

x

The horizontal coordinate of the position to move the shape to.

y

The vertical coordinate of the position to move the shape to.

DESCRIPTION

The GXMoveShapeTo function moves the shape referenced by the target parameter to the position specified by the x and y parameters. The position corresponds to a specific point in the shape's geometry:

• For point, line, and curve shapes, the point (x, y) corresponds to the first point in the shape's geometry.
• For rectangle, polygon, path, and bitmap shapes, the point (x, y) corresponds to the top-left corner of the bounding rectangle.
• For text, glyph, and layout shapes, the point (x, y) corresponds to the origin of the first glyph. If the shape contains no characters, this function has no effect.
• Other shapes (empty shapes, full shapes, and pictures) cannot be moved.

This function relocates the target shape in one of two ways:

• If the target shape's gxMapTransformShape attribute is cleared, the function recalculates the control points of the shape's geometry to effect the move.
• If the target shape's gxMapTransformShape attribute is set, this function is identical to the GXMoveTransformTo function; it recalculates the mapping matrix of the target shape's transform object to effect the move. If the target shape shares this transform object with other shapes, QuickDraw GX makes a copy of the transform object, associates the copy with the target shape, and makes changes to the copy.

The target shape can be any shape type. However, if the target shape is an empty shape, a full shape, or a picture shape, this function has no effect unless the shape's gxMapTransformShape attribute is set.

The horizontal and vertical coordinates are specified in geometry space.

SPECIAL CONSIDERATIONS

This function does not necessarily move the target shape to the position in local
space specified by the x and y parameters. Furthermore, if the shape's gxMapTransformShape attribute is set, this function does not necessarily move
the shape to the same position it would if the gxMapTransformShape attribute
were cleared:

• With the attribute cleared, this function modifies shape geometry so that, in geometry space, the shape is at the position specified in the x and y parameters. However, the function ignores the transform mapping, so the shape's resultant position in local space will be at (x, y) only if the transform mapping specifies no translation.
• With the attribute set, this function ignores shape geometry and sets the translation values in the shape's transform mapping to reflect the x and y parameters. Thus the shape's resultant position in local space will be at (x, y) only if its position in geometry space is at (0.0, 0.0).

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
shape_access_not_allowed	(debugging version)
Warnings
move_shape_out_of_range
graphic_type_cannot_be_moved
Notices (debugging version)
mapping_unaffected

SEE ALSO

For an example of the use of this function, see page 6-27.

To move a shape to a specified position by altering the mapping property of its transform object, you can also use the GXMoveTransformTo function, described on page 6-59.